The ssh2 npm package is a client and server module for SSH and SFTP written in pure JavaScript for node.js. It provides an interface to connect to and interact with SSH servers, allowing for the execution of commands, file transfers, local and remote port forwarding, and more.
Executing Commands on Remote Server
This code sample demonstrates how to execute a command (in this case, 'uptime') on a remote server using the ssh2 package.
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.exec('uptime', (err, stream) => {
if (err) throw err;
stream.on('close', (code, signal) => {
console.log('Stream :: close :: code: ' + code + ', signal: ' + signal);
conn.end();
}).on('data', (data) => {
console.log('STDOUT: ' + data);
}).stderr.on('data', (data) => {
console.log('STDERR: ' + data);
});
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: require('fs').readFileSync('/here/is/my/key')
});SFTP File Transfer
This code sample shows how to transfer a file from a local path to a remote path using SFTP with the ssh2 package.
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.sftp((err, sftp) => {
if (err) throw err;
sftp.fastPut(localPath, remotePath, {}, (err) => {
if (err) throw err;
console.log('File transferred successfully!');
conn.end();
});
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: require('fs').readFileSync('/here/is/my/key')
});TCP Port Forwarding
This code sample illustrates how to set up TCP port forwarding from the local machine to a remote destination using the ssh2 package.
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.forwardOut('127.0.0.1', 12345, 'www.google.com', 80, (err, stream) => {
if (err) throw err;
stream.on('close', () => {
console.log('TCP :: CLOSED');
conn.end();
}).on('data', (data) => {
console.log('TCP :: DATA: ' + data);
});
stream.end('GET / HTTP/1.1\r\nHost: www.google.com\r\nConnection: close\r\n\r\n');
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: require('fs').readFileSync('/here/is/my/key')
});node-ssh is an SSH2 client module that provides a higher-level API for interacting with SSH servers. It simplifies tasks like executing commands and handling file transfers. Compared to ssh2, node-ssh is built on top of ssh2 and offers a more promise-based API, which can be easier to use for some developers.
simple-ssh is another SSH client for node.js that aims to provide a simpler and more intuitive API than ssh2. It offers a chainable API for executing multiple commands in sequence. While it may be easier for beginners, it is not as feature-rich as ssh2 and may not be suitable for more complex SSH interactions.
SSH2 client and server modules written in pure JavaScript for node.js.
Development/testing is done against OpenSSH (8.7 currently).
Changes (breaking or otherwise) in v1.0.0 can be found here.
socksv5)cpu-features is set as an optional package dependency (you do not need to install it explicitly/separately from ssh2) that will be automatically built and used if possible. See the project's documentation for its own requirements.
npm install ssh2
const { readFileSync } = require('fs');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.exec('uptime', (err, stream) => {
if (err) throw err;
stream.on('close', (code, signal) => {
console.log('Stream :: close :: code: ' + code + ', signal: ' + signal);
conn.end();
}).on('data', (data) => {
console.log('STDOUT: ' + data);
}).stderr.on('data', (data) => {
console.log('STDERR: ' + data);
});
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: readFileSync('/path/to/my/key')
});
// example output:
// Client :: ready
// STDOUT: 17:41:15 up 22 days, 18:09, 1 user, load average: 0.00, 0.01, 0.05
//
// Stream :: exit :: code: 0, signal: undefined
// Stream :: close
const { readFileSync } = require('fs');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.shell((err, stream) => {
if (err) throw err;
stream.on('close', () => {
console.log('Stream :: close');
conn.end();
}).on('data', (data) => {
console.log('OUTPUT: ' + data);
});
stream.end('ls -l\nexit\n');
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
privateKey: readFileSync('/path/to/my/key')
});
// example output:
// Client :: ready
// STDOUT: Last login: Sun Jun 15 09:37:21 2014 from 192.168.100.100
//
// STDOUT: ls -l
// exit
//
// STDOUT: frylock@athf:~$ ls -l
//
// STDOUT: total 8
//
// STDOUT: drwxr-xr-x 2 frylock frylock 4096 Nov 18 2012 mydir
//
// STDOUT: -rw-r--r-- 1 frylock frylock 25 Apr 11 2013 test.txt
//
// STDOUT: frylock@athf:~$ exit
//
// STDOUT: logout
//
// Stream :: close
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.forwardOut('192.168.100.102', 8000, '127.0.0.1', 80, (err, stream) => {
if (err) throw err;
stream.on('close', () => {
console.log('TCP :: CLOSED');
conn.end();
}).on('data', (data) => {
console.log('TCP :: DATA: ' + data);
}).end([
'HEAD / HTTP/1.1',
'User-Agent: curl/7.27.0',
'Host: 127.0.0.1',
'Accept: */*',
'Connection: close',
'',
''
].join('\r\n'));
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
// example output:
// Client :: ready
// TCP :: DATA: HTTP/1.1 200 OK
// Date: Thu, 15 Nov 2012 13:52:58 GMT
// Server: Apache/2.2.22 (Ubuntu)
// X-Powered-By: PHP/5.4.6-1ubuntu1
// Last-Modified: Thu, 01 Jan 1970 00:00:00 GMT
// Content-Encoding: gzip
// Vary: Accept-Encoding
// Connection: close
// Content-Type: text/html; charset=UTF-8
//
//
// TCP :: CLOSED
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.forwardIn('127.0.0.1', 8000, (err) => {
if (err) throw err;
console.log('Listening for connections on server on port 8000!');
});
}).on('tcp connection', (info, accept, reject) => {
console.log('TCP :: INCOMING CONNECTION:');
console.dir(info);
accept().on('close', () => {
console.log('TCP :: CLOSED');
}).on('data', (data) => {
console.log('TCP :: DATA: ' + data);
}).end([
'HTTP/1.1 404 Not Found',
'Date: Thu, 15 Nov 2012 02:07:58 GMT',
'Server: ForwardedConnection',
'Content-Length: 0',
'Connection: close',
'',
''
].join('\r\n'));
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
// example output:
// Client :: ready
// Listening for connections on server on port 8000!
// (.... then from another terminal on the server: `curl -I http://127.0.0.1:8000`)
// TCP :: INCOMING CONNECTION: { destIP: '127.0.0.1',
// destPort: 8000,
// srcIP: '127.0.0.1',
// srcPort: 41969 }
// TCP DATA: HEAD / HTTP/1.1
// User-Agent: curl/7.27.0
// Host: 127.0.0.1:8000
// Accept: */*
//
//
// TCP :: CLOSED
const { Client } = require('ssh2');
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.sftp((err, sftp) => {
if (err) throw err;
sftp.readdir('foo', (err, list) => {
if (err) throw err;
console.dir(list);
conn.end();
});
});
}).connect({
host: '192.168.100.100',
port: 22,
username: 'frylock',
password: 'nodejsrules'
});
// example output:
// Client :: ready
// [ { filename: 'test.txt',
// longname: '-rw-r--r-- 1 frylock frylock 12 Nov 18 11:05 test.txt',
// attrs:
// { size: 12,
// uid: 1000,
// gid: 1000,
// mode: 33188,
// atime: 1353254750,
// mtime: 1353254744 } },
// { filename: 'mydir',
// longname: 'drwxr-xr-x 2 frylock frylock 4096 Nov 18 15:03 mydir',
// attrs:
// { size: 1048576,
// uid: 1000,
// gid: 1000,
// mode: 16877,
// atime: 1353269007,
// mtime: 1353269007 } } ]
const { Client } = require('ssh2');
const conn1 = new Client();
const conn2 = new Client();
// Checks uptime on 10.1.1.40 via 192.168.1.1
conn1.on('ready', () => {
console.log('FIRST :: connection ready');
// Alternatively, you could use something like netcat or socat with exec()
// instead of forwardOut(), depending on what the server allows
conn1.forwardOut('127.0.0.1', 12345, '10.1.1.40', 22, (err, stream) => {
if (err) {
console.log('FIRST :: forwardOut error: ' + err);
return conn1.end();
}
conn2.connect({
sock: stream,
username: 'user2',
password: 'password2',
});
});
}).connect({
host: '192.168.1.1',
username: 'user1',
password: 'password1',
});
conn2.on('ready', () => {
// This connection is the one to 10.1.1.40
console.log('SECOND :: connection ready');
conn2.exec('uptime', (err, stream) => {
if (err) {
console.log('SECOND :: exec error: ' + err);
return conn1.end();
}
stream.on('close', () => {
conn1.end(); // close parent (and this) connection
}).on('data', (data) => {
console.log(data.toString());
});
});
});
const { Socket } = require('net');
const { Client } = require('ssh2');
const conn = new Client();
conn.on('x11', (info, accept, reject) => {
const xserversock = new net.Socket();
xserversock.on('connect', () => {
const xclientsock = accept();
xclientsock.pipe(xserversock).pipe(xclientsock);
});
// connects to localhost:0.0
xserversock.connect(6000, 'localhost');
});
conn.on('ready', () => {
conn.exec('xeyes', { x11: true }, (err, stream) => {
if (err) throw err;
let code = 0;
stream.on('close', () => {
if (code !== 0)
console.log('Do you have X11 forwarding enabled on your SSH server?');
conn.end();
}).on('exit', (exitcode) => {
code = exitcode;
});
});
}).connect({
host: '192.168.1.1',
username: 'foo',
password: 'bar'
});
const socks = require('socksv5');
const { Client } = require('ssh2');
const sshConfig = {
host: '192.168.100.1',
port: 22,
username: 'nodejs',
password: 'rules'
};
socks.createServer((info, accept, deny) => {
// NOTE: you could just use one ssh2 client connection for all forwards, but
// you could run into server-imposed limits if you have too many forwards open
// at any given time
const conn = new Client();
conn.on('ready', () => {
conn.forwardOut(info.srcAddr,
info.srcPort,
info.dstAddr,
info.dstPort,
(err, stream) => {
if (err) {
conn.end();
return deny();
}
const clientSocket = accept(true);
if (clientSocket) {
stream.pipe(clientSocket).pipe(stream).on('close', () => {
conn.end();
});
} else {
conn.end();
}
});
}).on('error', (err) => {
deny();
}).connect(sshConfig);
}).listen(1080, 'localhost', () => {
console.log('SOCKSv5 proxy server started on port 1080');
}).useAuth(socks.auth.None());
// test with cURL:
// curl -i --socks5 localhost:1080 google.com
const http = require('http');
const { Client, HTTPAgent, HTTPSAgent } = require('ssh2');
const sshConfig = {
host: '192.168.100.1',
port: 22,
username: 'nodejs',
password: 'rules'
};
// Use `HTTPSAgent` instead for an HTTPS request
const agent = new HTTPAgent(sshConfig);
http.get({
host: '192.168.200.1',
agent,
headers: { Connection: 'close' }
}, (res) => {
console.log(res.statusCode);
console.dir(res.headers);
res.resume();
});
const { Client } = require('ssh2');
const xmlhello = `
<?xml version="1.0" encoding="UTF-8"?>
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>urn:ietf:params:netconf:base:1.0</capability>
</capabilities>
</hello>]]>]]>`;
const conn = new Client();
conn.on('ready', () => {
console.log('Client :: ready');
conn.subsys('netconf', (err, stream) => {
if (err) throw err;
stream.on('data', (data) => {
console.log(data);
}).write(xmlhello);
});
}).connect({
host: '1.2.3.4',
port: 22,
username: 'blargh',
password: 'honk'
});
const { timingSafeEqual } = require('crypto');
const { readFileSync } = require('fs');
const { inspect } = require('util');
const { utils: { parseKey }, Server } = require('ssh2');
const allowedUser = Buffer.from('foo');
const allowedPassword = Buffer.from('bar');
const allowedPubKey = parseKey(readFileSync('foo.pub'));
function checkValue(input, allowed) {
const autoReject = (input.length !== allowed.length);
if (autoReject) {
// Prevent leaking length information by always making a comparison with the
// same input when lengths don't match what we expect ...
allowed = input;
}
const isMatch = timingSafeEqual(input, allowed);
return (!autoReject && isMatch);
}
new Server({
hostKeys: [readFileSync('host.key')]
}, (client) => {
console.log('Client connected!');
client.on('authentication', (ctx) => {
let allowed = true;
if (!checkValue(Buffer.from(ctx.username), allowedUser))
allowed = false;
switch (ctx.method) {
case 'password':
if (!checkValue(Buffer.from(ctx.password), allowedPassword))
return ctx.reject();
break;
case 'publickey':
if (ctx.key.algo !== allowedPubKey.type
|| !checkValue(ctx.key.data, allowedPubKey.getPublicSSH())
|| (ctx.signature && allowedPubKey.verify(ctx.blob, ctx.signature, ctx.hashAlgo) !== true)) {
return ctx.reject();
}
break;
default:
return ctx.reject();
}
if (allowed)
ctx.accept();
else
ctx.reject();
}).on('ready', () => {
console.log('Client authenticated!');
client.on('session', (accept, reject) => {
const session = accept();
session.once('exec', (accept, reject, info) => {
console.log('Client wants to execute: ' + inspect(info.command));
const stream = accept();
stream.stderr.write('Oh no, the dreaded errors!\n');
stream.write('Just kidding about the errors!\n');
stream.exit(0);
stream.end();
});
});
}).on('close', () => {
console.log('Client disconnected');
});
}).listen(0, '127.0.0.1', function() {
console.log('Listening on port ' + this.address().port);
});
const { timingSafeEqual } = require('crypto');
const { readFileSync } = require('fs');
const { inspect } = require('util');
const {
Server,
sftp: {
OPEN_MODE,
STATUS_CODE,
},
} = require('ssh2');
const allowedUser = Buffer.from('foo');
const allowedPassword = Buffer.from('bar');
function checkValue(input, allowed) {
const autoReject = (input.length !== allowed.length);
if (autoReject) {
// Prevent leaking length information by always making a comparison with the
// same input when lengths don't match what we expect ...
allowed = input;
}
const isMatch = timingSafeEqual(input, allowed);
return (!autoReject && isMatch);
}
// This simple SFTP server implements file uploading where the contents get
// ignored ...
new ssh2.Server({
hostKeys: [readFileSync('host.key')]
}, (client) => {
console.log('Client connected!');
client.on('authentication', (ctx) => {
let allowed = true;
if (!checkValue(Buffer.from(ctx.username), allowedUser))
allowed = false;
switch (ctx.method) {
case 'password':
if (!checkValue(Buffer.from(ctx.password), allowedPassword))
return ctx.reject();
break;
default:
return ctx.reject();
}
if (allowed)
ctx.accept();
else
ctx.reject();
}).on('ready', () => {
console.log('Client authenticated!');
client.on('session', (accept, reject) => {
const session = accept();
session.on('sftp', (accept, reject) => {
console.log('Client SFTP session');
const openFiles = new Map();
let handleCount = 0;
const sftp = accept();
sftp.on('OPEN', (reqid, filename, flags, attrs) => {
// Only allow opening /tmp/foo.txt for writing
if (filename !== '/tmp/foo.txt' || !(flags & OPEN_MODE.WRITE))
return sftp.status(reqid, STATUS_CODE.FAILURE);
// Create a fake handle to return to the client, this could easily
// be a real file descriptor number for example if actually opening
// a file on disk
const handle = Buffer.alloc(4);
openFiles.set(handleCount, true);
handle.writeUInt32BE(handleCount++, 0);
console.log('Opening file for write')
sftp.handle(reqid, handle);
}).on('WRITE', (reqid, handle, offset, data) => {
if (handle.length !== 4
|| !openFiles.has(handle.readUInt32BE(0))) {
return sftp.status(reqid, STATUS_CODE.FAILURE);
}
// Fake the write operation
sftp.status(reqid, STATUS_CODE.OK);
console.log('Write to file at offset ${offset}: ${inspect(data)}');
}).on('CLOSE', (reqid, handle) => {
let fnum;
if (handle.length !== 4
|| !openFiles.has(fnum = handle.readUInt32BE(0))) {
return sftp.status(reqid, STATUS_CODE.FAILURE);
}
console.log('Closing file');
openFiles.delete(fnum);
sftp.status(reqid, STATUS_CODE.OK);
});
});
});
}).on('close', () => {
console.log('Client disconnected');
});
}).listen(0, '127.0.0.1', function() {
console.log('Listening on port ' + this.address().port);
});
const { utils: { generateKeyPair, generateKeyPairSync } } = require('ssh2');
// Generate unencrypted ED25519 SSH key synchronously
let keys = generateKeyPairSync('ed25519');
// ... use `keys.public` and `keys.private`
// Generate unencrypted ECDSA SSH key synchronously with a comment set
keys = generateKeyPairSync('ecdsa', { bits: 256, comment: 'node.js rules!' });
// ... use `keys.public` and `keys.private`
// Generate encrypted RSA SSH key asynchronously
generateKeyPair(
'rsa',
{ bits: 2048, passphrase: 'foobarbaz', cipher: 'aes256-cbc' },
(err, keys) => {
if (err) throw err;
// ... use `keys.public` and `keys.private`
}
);
You can find more examples in the examples directory of this repository.
require('ssh2').Client is the Client constructor.
require('ssh2').Server is the Server constructor.
require('ssh2').utils is an object containing some useful utilities.
require('ssh2').HTTPAgent is an http.Agent constructor.
require('ssh2').HTTPSAgent is an https.Agent constructor. Its API is the same as HTTPAgent except it's for HTTPS connections.
require('ssh2').AgentProtocol is a Duplex stream class that aids in communicating over the OpenSSH agent protocol.
require('ssh2').BaseAgent is a base class for creating custom authentication agents.
require('ssh2').createAgent is a helper function that creates a new agent instance using the same logic as the agent configuration option: if the platform is Windows and it's the value "pageant", it creates a PageantAgent, otherwise if it's not a path to a Windows pipe it creates a CygwinAgent. In all other cases, it creates an OpenSSHAgent.
require('ssh2').CygwinAgent is an agent class implementation that communicates with agents in a Cygwin environment.
require('ssh2').OpenSSHAgent is an agent class implementation that communicates with OpenSSH agents over a UNIX socket.
require('ssh2').PageantAgent is an agent class implementation that communicates with Pageant agent processes.
banner(< string >message, < string >language) - A notice was sent by the server upon connection.
change password(< string >prompt, < function >done) - If using password-based user authentication, the server has requested that the user's password be changed. Call done with the new password.
close() - The socket was closed.
end() - The socket was disconnected.
error(< Error >err) - An error occurred. A 'level' property indicates 'client-socket' for socket-level errors and 'client-ssh' for SSH disconnection messages. In the case of 'client-ssh' messages, there may be a 'description' property that provides more detail.
handshake(< object >negotiated) - Emitted when a handshake has completed (either initial or rekey). negotiated contains the negotiated details of the handshake and is of the form:
// In this particular case `mac` is empty because there is no separate MAC
// because it's integrated into AES in GCM mode
{ kex: 'ecdh-sha2-nistp256',
srvHostKey: 'rsa-sha2-512',
cs: { // Client to server algorithms
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
},
sc: { // Server to client algorithms
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
}
}
hostkeys(< array >keys) - Emitted when the server announces its available host keys. keys is the list of parsed (using parseKey()) host public keys.
keyboard-interactive(< string >name, < string >instructions, < string >instructionsLang, < array >prompts, < function >finish) - The server is asking for replies to the given prompts for keyboard-interactive user authentication. name is generally what you'd use as a window title (for GUI apps). prompts is an array of { prompt: 'Password: ', echo: false } style objects (here echo indicates whether user input should be displayed on the screen). The answers for all prompts must be provided as an array of strings and passed to finish when you are ready to continue. Note: It's possible for the server to come back and ask more questions.
ready() - Authentication was successful.
rekey() - Emitted when a rekeying operation has completed (either client or server-initiated).
tcp connection(< object >details, < function >accept, < function >reject) - An incoming forwarded TCP connection is being requested. Calling accept accepts the connection and returns a Channel object. Calling reject rejects the connection and no further action is needed. details contains:
destIP - string - The remote IP the connection was received on (given in earlier call to forwardIn()).
destPort - integer - The remote port the connection was received on (given in earlier call to forwardIn()).
srcIP - string - The originating IP of the connection.
srcPort - integer - The originating port of the connection.
unix connection(< object >details, < function >accept, < function >reject) - An incoming forwarded UNIX socket connection is being requested. Calling accept accepts the connection and returns a Channel object. Calling reject rejects the connection and no further action is needed. details contains:
x11(< object >details, < function >accept, < function >reject) - An incoming X11 connection is being requested. Calling accept accepts the connection and returns a Channel object. Calling reject rejects the connection and no further action is needed. details contains:
srcIP - string - The originating IP of the connection.
srcPort - integer - The originating port of the connection.
(constructor)() - Creates and returns a new Client instance.
connect(< object >config) - (void) - Attempts a connection to a server using the information given in config:
agent - string - Path to ssh-agent's UNIX socket for ssh-agent-based user authentication. Windows users: set to 'pageant' for authenticating with Pageant or (actual) path to a cygwin "UNIX socket." Default: (none)
agentForward - boolean - Set to true to use OpenSSH agent forwarding (auth-agent@openssh.com) for the life of the connection. agent must also be set to use this feature. Default: false
algorithms - object - This option allows you to explicitly override the default transport layer algorithms used for the connection. The value for each category must either be an array of valid algorithm names to set an exact list (with the most preferable first) or an object containing append, prepend, and/or remove properties that each contain an array of algorithm names or RegExps to match to adjust default lists for each category. Valid keys:
cipher - mixed - Ciphers.
chacha20-poly1305@openssh.com (priority of chacha20-poly1305 may vary depending upon CPU and/or optional binding availability)aes128-gcmaes128-gcm@openssh.comaes256-gcmaes256-gcm@openssh.comaes128-ctraes192-ctraes256-ctr3des-cbcaes256-cbcaes192-cbcaes128-cbcarcfour256arcfour128arcfourblowfish-cbccast128-cbccompress - mixed - Compression algorithms.
nonezlib@openssh.comzlibhmac - mixed - (H)MAC algorithms.
hmac-sha2-256-etm@openssh.comhmac-sha2-512-etm@openssh.comhmac-sha1-etm@openssh.comhmac-sha2-256hmac-sha2-512hmac-sha1hmac-md5hmac-sha2-256-96hmac-sha2-512-96hmac-ripemd160hmac-sha1-96hmac-md5-96kex - mixed - Key exchange algorithms.
curve25519-sha256 (node v14.0.0+)curve25519-sha256@libssh.org (node v14.0.0+)ecdh-sha2-nistp256ecdh-sha2-nistp384ecdh-sha2-nistp521diffie-hellman-group-exchange-sha256diffie-hellman-group14-sha256diffie-hellman-group15-sha512diffie-hellman-group16-sha512diffie-hellman-group17-sha512diffie-hellman-group18-sha512diffie-hellman-group-exchange-sha1diffie-hellman-group14-sha1diffie-hellman-group1-sha1serverHostKey - mixed - Server host key formats.
ssh-ed25519 (node v12.0.0+)ecdsa-sha2-nistp256ecdsa-sha2-nistp384ecdsa-sha2-nistp521rsa-sha2-512rsa-sha2-256ssh-rsassh-dssauthHandler - mixed - Must be an array of objects as described below, an array of strings containing valid authentication method names (username and credentials are pulled from the object passed to connect()), or a function with parameters (methodsLeft, partialSuccess, callback) where methodsLeft and partialSuccess are null on the first authentication attempt, otherwise are an array and boolean respectively. Return or call callback() with either the name of the authentication method or an object containing the method name along with method-specific details to try next (return/pass false to signal no more methods to try). Valid method names are: 'none', 'password', 'publickey', 'agent', 'keyboard-interactive', 'hostbased'. Default: function that follows a set method order: None -> Password -> Private Key -> Agent (-> keyboard-interactive if tryKeyboard is true) -> Hostbased
When returning or calling callback() with an object, it can take one of the following forms:
{
type: 'none',
username: 'foo',
}
{
type: 'password'
username: 'foo',
password: 'bar',
}
{
type: 'publickey'
username: 'foo',
// Can be a string, Buffer, or parsed key containing a private key
key: ...,
// `passphrase` only required for encrypted keys
passphrase: ...,
}
{
type: 'hostbased'
username: 'foo',
localHostname: 'baz',
localUsername: 'quux',
// Can be a string, Buffer, or parsed key containing a private key
key: ...,
// `passphrase` only required for encrypted keys
passphrase: ...,
}
{
type: 'agent'
username: 'foo',
// Can be a string that is interpreted exactly like the `agent`
// connection config option or can be a custom agent
// object/instance that extends and implements `BaseAgent`
agent: ...,
}
{
type: 'keyboard-interactive'
username: 'foo',
// This works exactly the same way as a 'keyboard-interactive'
// Client event handler
prompt: (name, instructions, instructionsLang, prompts, finish) => {
// ...
},
}
debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)
forceIPv4 - boolean - Only connect via resolved IPv4 address for host. Default: false
forceIPv6 - boolean - Only connect via resolved IPv6 address for host. Default: false
host - string - Hostname or IP address of the server. Default: 'localhost'
hostHash - string - Any valid hash algorithm supported by node. The host's key is hashed using this algorithm and passed to the hostVerifier function as a hex string. Default: (none)
hostVerifier - function - Function with parameters (key[, callback]) for verifying host keys, where key is either a hex string of the hash of the key if hostHash was set, otherwise it is the raw host key in Buffer form. Use utils.parseKey() to get the host key type. Return true to continue with the handshake or false to reject and disconnect, or call callback() with true or false if you need to perform asynchronous verification. Default: (auto-accept if hostVerifier is not set)
keepaliveCountMax - integer - How many consecutive, unanswered SSH-level keepalive packets that can be sent to the server before disconnection (similar to OpenSSH's ServerAliveCountMax config option). Default: 3
keepaliveInterval - integer - How often (in milliseconds) to send SSH-level keepalive packets to the server (in a similar way as OpenSSH's ServerAliveInterval config option). Set to 0 to disable. Default: 0
localAddress - string - IP address of the network interface to use to connect to the server. Default: (none -- determined by OS)
localHostname - string - Along with localUsername and privateKey, set this to a non-empty string for hostbased user authentication. Default: (none)
localPort - string - The local port number to connect from. Default: (none -- determined by OS)
localUsername - string - Along with localHostname and privateKey, set this to a non-empty string for hostbased user authentication. Default: (none)
passphrase - string - For an encrypted privateKey, this is the passphrase used to decrypt it. Default: (none)
password - string - Password for password-based user authentication. Default: (none)
port - integer - Port number of the server. Default: 22
privateKey - mixed - Buffer or string that contains a private key for either key-based or hostbased user authentication (OpenSSH format). Default: (none)
readyTimeout - integer - How long (in milliseconds) to wait for the SSH handshake to complete. Default: 20000
sock - ReadableStream - A ReadableStream to use for communicating with the server instead of creating and using a new TCP connection (useful for connection hopping).
strictVendor - boolean - Performs a strict server vendor check before sending vendor-specific requests, etc. (e.g. check for OpenSSH server when using openssh_noMoreSessions()) Default: true
tryKeyboard - boolean - Try keyboard-interactive user authentication if primary user authentication method fails. If you set this to true, you need to handle the keyboard-interactive event. Default: false
username - string - Username for authentication. Default: (none)
end() - (void) - Disconnects the socket.
exec(< string >command[, < object >options], < function >callback) - (void) - Executes command on the server. callback has 2 parameters: < Error >err, < Channel >stream. Valid options properties are:
env - object - An environment to use for the execution of the command.
pty - mixed - Set to true to allocate a pseudo-tty with defaults, or an object containing specific pseudo-tty settings (see 'Pseudo-TTY settings'). Setting up a pseudo-tty can be useful when working with remote processes that expect input from an actual terminal (e.g. sudo's password prompt).
x11 - mixed - Set to true to use defaults below, set to a number to specify a specific screen number, or an object with the following valid properties:
cookie - mixed - The authentication cookie. Can be a hex string or a Buffer containing the raw cookie value (which will be converted to a hex string). Default: (random 16 byte value)
protocol - string - The authentication protocol name. Default: 'MIT-MAGIC-COOKIE-1'
screen - number - Screen number to use Default: 0
single - boolean - Allow just a single connection? Default: false
forwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Bind to remoteAddr on remotePort on the server and forward incoming TCP connections. callback has 2 parameters: < Error >err, < integer >port (port is the assigned port number if remotePort was 0). Here are some special values for remoteAddr and their associated binding behaviors:
'' - Connections are to be accepted on all protocol families supported by the server.
'0.0.0.0' - Listen on all IPv4 addresses.
'::' - Listen on all IPv6 addresses.
'localhost' - Listen on all protocol families supported by the server on loopback addresses only.
'127.0.0.1' and '::1' - Listen on the loopback interfaces for IPv4 and IPv6, respectively.
forwardOut(< string >srcIP, < integer >srcPort, < string >dstIP, < integer >dstPort, < function >callback) - (void) - Open a connection with srcIP and srcPort as the originating address and port and dstIP and dstPort as the remote destination address and port. callback has 2 parameters: < Error >err, < Channel >stream.
openssh_forwardInStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that binds to a UNIX domain socket at socketPath on the server and forwards incoming connections. callback has 1 parameter: < Error >err.
openssh_forwardOutStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that opens a connection to a UNIX domain socket at socketPath on the server. callback has 2 parameters: < Error >err, < Channel >stream.
openssh_noMoreSessions(< function >callback) - (void) - OpenSSH extension that sends a request to reject any new sessions (e.g. exec, shell, sftp, subsys) for this connection. callback has 1 parameter: < Error >err.
openssh_unforwardInStreamLocal(< string >socketPath, < function >callback) - (void) - OpenSSH extension that unbinds from a UNIX domain socket at socketPath on the server and stops forwarding incoming connections. callback has 1 parameter: < Error >err.
rekey([< function >callback]) - (void) - Initiates a rekey with the server. If callback is supplied, it is added as a one-time handler for the rekey event.
setNoDelay([< boolean >noDelay]) - Client - Calls setNoDelay() on the underlying socket. Disabling Nagle's algorithm improves latency at the expense of lower throughput.
sftp(< function >callback) - (void) - Starts an SFTP session. callback has 2 parameters: < Error >err, < SFTP >sftp. For methods available on sftp, see the SFTP client documentation.
shell([[< mixed >window,] < object >options]< function >callback) - (void) - Starts an interactive shell session on the server, with an optional window object containing pseudo-tty settings (see 'Pseudo-TTY settings'). If window === false, then no pseudo-tty is allocated. options supports the x11 and env options as described in exec(). callback has 2 parameters: < Error >err, < Channel >stream.
subsys(< string >subsystem, < function >callback) - (void) - Invokes subsystem on the server. callback has 2 parameters: < Error >err, < Channel >stream.
unforwardIn(< string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Unbind from remoteAddr on remotePort on the server and stop forwarding incoming TCP connections. Until callback is called, more connections may still come in. callback has 1 parameter: < Error >err.
connection(< Connection >client, < object >info) - A new client has connected. info contains the following properties:
family - string - The remoteFamily of the connection.
header - object - Information about the client's header:
identRaw - string - The raw client identification string.
versions - object - Various version information:
protocol - string - The SSH protocol version (always 1.99 or 2.0).
software - string - The software name and version of the client.
comments - string - Any text that comes after the software name/version.
Example: the identification string SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2 would be parsed as:
{
identRaw: 'SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2',
version: {
protocol: '2.0',
software: 'OpenSSH_6.6.1p1'
},
comments: 'Ubuntu-2ubuntu2'
}
ip - string - The remoteAddress of the connection.
port - integer - The remotePort of the connection.
(constructor)(< object >config[, < function >connectionListener]) - Creates and returns a new Server instance. Server instances also have the same methods/properties/events as net.Server. connectionListener if supplied, is added as a connection listener. Valid config properties:
algorithms - object - This option allows you to explicitly override the default transport layer algorithms used for incoming client connections. Each value must be an array of valid algorithms for that category. The order of the algorithms in the arrays are important, with the most favorable being first. For a list of valid and default algorithm names, please review the documentation for the version of ssh2 used by this module. Valid keys:
cipher - array - Ciphers.
compress - array - Compression algorithms.
hmac - array - (H)MAC algorithms.
kex - array - Key exchange algorithms.
serverHostKey - array - Server host key formats.
banner - string - A message that is sent to clients once, right before authentication begins. Default: (none)
debug - function - Set this to a function that receives a single string argument to get detailed (local) debug information. Default: (none)
greeting - string - A message that is sent to clients immediately upon connection, before handshaking begins. Note: Most clients usually ignore this. Default: (none)
highWaterMark - integer - This is the highWaterMark to use for the parser stream. Default: 32 * 1024
hostKeys - array - An array of either Buffers/strings that contain host private keys or objects in the format of { key: <Buffer/string>, passphrase: <string> } for encrypted private keys. (Required) Default: (none)
ident - string - A custom server software name/version identifier. Default: 'ssh2js' + moduleVersion + 'srv'
injectSocket(< DuplexStream >socket) - Injects a bidirectional stream as though it were a TCP socket connection. Additionally, socket should include net.Socket-like properties to ensure the best compatibility (e.g. socket.remoteAddress, socket.remotePort, socket.remoteFamily).
authentication(< AuthContext >ctx) - The client has requested authentication. ctx.username contains the client username, ctx.method contains the requested authentication method, and ctx.accept() and ctx.reject([< Array >authMethodsLeft[, < Boolean >isPartialSuccess]]) are used to accept or reject the authentication request respectively. 'abort' is emitted if the client aborts the authentication request. Other properties/methods available on ctx depends on the ctx.method of authentication the client has requested:
hostbased:
blob - Buffer - This contains the data to be verified that is passed to (along with the signature) key.verify() where key is a public key parsed with parseKey().
key - object - Contains information about the public key sent by the client:
algo - string - The name of the key algorithm (e.g. ssh-rsa).
data - Buffer - The actual key data.
localHostname - string - The local hostname provided by the client.
localUsername - string - The local username provided by the client.
signature - Buffer - This contains a signature to be verified that is passed to (along with the blob) key.verify() where key is a public key parsed with parseKey().
hashAlgo - mixed - This is either undefined or a string containing an explicit hash algorithm to be used during verification (passed to key.verify()).
keyboard-interactive:
prompt(< array >prompts[, < string >title[, < string >instructions]], < function >callback) - (void) - Send prompts to the client. prompts is an array of { prompt: 'Prompt text', echo: true } objects (prompt being the prompt text and echo indicating whether the client's response to the prompt should be echoed to their display). callback is called with (responses), where responses is an array of string responses matching up to the prompts.
submethods - array - A list of preferred authentication "sub-methods" sent by the client. This may be used to determine what (if any) prompts to send to the client.
password:
password - string - This is the password sent by the client.
requestChange(< string >prompt, < function >callback) - (void) - Sends a password change request to the client. callback is called with (newPassword), where newPassword is the new password supplied by the client. You may accept, reject, or prompt for another password change after callback is called.
publickey:
blob - mixed - If the value is undefined, the client is only checking the validity of the key. If the value is a Buffer, then this contains the data to be verified that is passed to (along with the signature) key.verify() where key is a public key parsed with parseKey().
key - object - Contains information about the public key sent by the client:
algo - string - The name of the key algorithm (e.g. ssh-rsa).
data - Buffer - The actual key data.
signature - mixed - If the value is undefined, the client is only checking the validity of the key. If the value is a Buffer, then this contains a signature to be verified that is passed to (along with the blob) key.verify() where key is a public key parsed with parseKey().
hashAlgo - mixed - This is either undefined or a string containing an explicit hash algorithm to be used during verification (passed to key.verify()).
close() - The client socket was closed.
end() - The client socket disconnected.
error(< Error >err) - An error occurred.
handshake(< object >negotiated) - Emitted when a handshake has completed (either initial or rekey). negotiated contains the negotiated details of the handshake and is of the form:
// In this particular case `mac` is empty because there is no separate MAC
// because it's integrated into AES in GCM mode
{ kex: 'ecdh-sha2-nistp256',
srvHostKey: 'rsa-sha2-512',
cs: { // Client to server algorithms
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
},
sc: { // Server to client algorithms
cipher: 'aes128-gcm',
mac: '',
compress: 'none',
lang: ''
}
}
openssh.streamlocal(< function >accept, < function >reject, < object >info) - Emitted when the client has requested a connection to a UNIX domain socket. accept() returns a new Channel instance representing the connection. info contains:
ready() - Emitted when the client has been successfully authenticated.
rekey() - Emitted when a rekeying operation has completed (either client or server-initiated).
request(< mixed >accept, < mixed >reject, < string >name, < object >info) - Emitted when the client has sent a global request for name (e.g. tcpip-forward or cancel-tcpip-forward). accept and reject are functions if the client requested a response. If bindPort === 0, you should pass the chosen port to accept() so that the client will know what port was bound. info contains additional details about the request:
cancel-tcpip-forward and tcpip-forward:
bindAddr - string - The IP address to start/stop binding to.
bindPort - integer - The port to start/stop binding to.
cancel-streamlocal-forward@openssh.com and streamlocal-forward@openssh.com:
session(< function >accept, < function >reject) - Emitted when the client has requested a new session. Sessions are used to start interactive shells, execute commands, request X11 forwarding, etc. accept() returns a new Session instance.
tcpip(< function >accept, < function >reject, < object >info) - Emitted when the client has requested an outbound (TCP) connection. accept() returns a new Channel instance representing the connection. info contains:
destIP - string - Destination IP address of outgoing connection.
destPort - string - Destination port of outgoing connection.
srcIP - string - Source IP address of outgoing connection.
srcPort - string - Source port of outgoing connection.
end() - (void) - Closes the client connection.
forwardOut(< string >boundAddr, < integer >boundPort, < string >remoteAddr, < integer >remotePort, < function >callback) - (void) - Alert the client of an incoming TCP connection on boundAddr on port boundPort from remoteAddr on port remotePort. callback has 2 parameters: < Error >err, < Channel >stream.
openssh_forwardOutStreamLocal(< string >socketPath, < function >callback) - (void) - Alert the client of an incoming UNIX domain socket connection on socketPath. callback has 2 parameters: < Error >err, < Channel >stream.
rekey([< function >callback]) - (void) - Initiates a rekey with the client. If callback is supplied, it is added as a one-time handler for the rekey event.
setNoDelay([< boolean >noDelay]) - Connection - Calls setNoDelay() on the underlying socket. Disabling Nagle's algorithm improves latency at the expense of lower throughput.
x11(< string >originAddr, < integer >originPort, < function >callback) - (void) - Alert the client of an incoming X11 client connection from originAddr on port originPort. callback has 2 parameters: < Error >err, < Channel >stream.
auth-agent(< mixed >accept, < mixed >reject) - The client has requested incoming ssh-agent requests be forwarded to them. accept and reject are functions if the client requested a response.
close() - The session was closed.
env(< mixed >accept, < mixed >reject, < object >info) - The client requested an environment variable to be set for this session. accept and reject are functions if the client requested a response. info has these properties:
key - string - The environment variable's name.
value - string - The environment variable's value.
exec(< mixed >accept, < mixed >reject, < object >info) - The client has requested execution of a command string. accept and reject are functions if the client requested a response. accept() returns a Channel for the command execution. info has these properties:
pty(< mixed >accept, < mixed >reject, < object >info) - The client requested allocation of a pseudo-TTY for this session. accept and reject are functions if the client requested a response. info has these properties:
term - string - The terminal type for the pseudo-TTY.
cols - integer - The number of columns for the pseudo-TTY.
height - integer - The height of the pseudo-TTY in pixels.
modes - object - Contains the requested terminal modes of the pseudo-TTY keyed on the mode name with the value being the mode argument. (See the table at the end for valid names).
rows - integer - The number of rows for the pseudo-TTY.
width - integer - The width of the pseudo-TTY in pixels.
sftp(< mixed >accept, < mixed >reject) - The client has requested the SFTP subsystem. accept and reject are functions if the client requested a response. accept() returns an SFTP instance in server mode (see the SFTP documentation for details). info has these properties:
shell(< mixed >accept, < mixed >reject) - The client has requested an interactive shell. accept and reject are functions if the client requested a response. accept() returns a Channel for the interactive shell.
signal(< mixed >accept, < mixed >reject, < object >info) - The client has sent a signal. accept and reject are functions if the client requested a response. info has these properties:
SIGUSR1).subsystem(< mixed >accept, < mixed >reject, < object >info) - The client has requested an arbitrary subsystem. accept and reject are functions if the client requested a response. accept() returns a Channel for the subsystem. info has these properties:
window-change(< mixed >accept, < mixed >reject, < object >info) - The client reported a change in window dimensions during this session. accept and reject are functions if the client requested a response. info has these properties:
cols - integer - The new number of columns for the client window.
height - integer - The new height of the client window in pixels.
rows - integer - The new number of rows for the client window.
width - integer - The new width of the client window in pixels.
x11(< mixed >accept, < mixed >reject, < object >info) - The client requested X11 forwarding. accept and reject are functions if the client requested a response. info has these properties:
cookie - string - The X11 authentication cookie encoded in hexadecimal.
protocol - string - The name of the X11 authentication method used (e.g. MIT-MAGIC-COOKIE-1).
screen - integer - The screen number to forward X11 connections for.
single - boolean - true if only a single connection should be forwarded.
This is a normal streams2 Duplex Stream (used both by clients and servers), with the following changes:
A boolean property allowHalfOpen exists and behaves similarly to the property of the same name for net.Socket. When the stream's end() is called, if allowHalfOpen is true, only EOF will be sent (the server can still send data if they have not already sent EOF). The default value for this property is true.
A close event is emitted once the channel is completely closed on both the client and server.
Client-specific:
For exec():
An exit event may (the SSH2 spec says it is optional) be emitted when the process finishes. If the process finished normally, the process's return value is passed to the exit callback. If the process was interrupted by a signal, the following are passed to the exit callback: null, < string >signalName, < boolean >didCoreDump, < string >description.
If there was an exit event, the close event will be passed the same arguments for convenience.
A stderr property contains a Readable stream that represents output from stderr.
For exec() and shell():
The readable side represents stdout and the writable side represents stdin.
setWindow(< integer >rows, < integer >cols, < integer >height, < integer >width) - (void) - Lets the server know that the local terminal window has been resized. The meaning of these arguments are described in the 'Pseudo-TTY settings' section.
signal(< string >signalName) - (void) - Sends a POSIX signal to the current process on the server. Valid signal names are: 'ABRT', 'ALRM', 'FPE', 'HUP', 'ILL', 'INT', 'KILL', 'PIPE', 'QUIT', 'SEGV', 'TERM', 'USR1', and 'USR2'. Some server implementations may ignore this request if they do not support signals. Note: If you are trying to send SIGINT and you find signal() doesn't work, try writing '\x03' to the Channel stream instead.
Server-specific:
For exec-enabled channel instances there is an additional method available that may be called right before you close the channel. It has two different signatures:
exit(< integer >exitCode) - (void) - Sends an exit status code to the client.
exit(< string >signalName[, < boolean >coreDumped[, < string >errorMsg]]) - (void) - Sends an exit status code to the client.
For exec and shell-enabled channel instances, channel.stderr is a writable stream.
cols - < integer > - Number of columns. Default: 80
height - < integer > - Height in pixels. Default: 480
modes - < object > - An object containing Terminal Modes as keys, with each value set to each mode argument. Default: null
rows - < integer > - Number of rows. Default: 24
term - < string > - The value to use for $TERM. Default: 'vt100'
width - < integer > - Width in pixels. Default: 640
rows and cols override width and height when rows and cols are non-zero.
Pixel dimensions refer to the drawable area of the window.
Zero dimension parameters are ignored.
| Name | Description |
|---|---|
| CS7 | 7 bit mode. |
| CS8 | 8 bit mode. |
| ECHOCTL | Echo control characters as ^(Char). |
| ECHO | Enable echoing. |
| ECHOE | Visually erase chars. |
| ECHOKE | Visual erase for line kill. |
| ECHOK | Kill character discards current line. |
| ECHONL | Echo NL even if ECHO is off. |
| ICANON | Canonicalize input lines. |
| ICRNL | Map CR to NL on input. |
| IEXTEN | Enable extensions. |
| IGNCR | Ignore CR on input. |
| IGNPAR | The ignore parity flag. The parameter SHOULD be 0 if this flag is FALSE, and 1 if it is TRUE. |
| IMAXBEL | Ring bell on input queue full. |
| INLCR | Map NL into CR on input. |
| INPCK | Enable checking of parity errors. |
| ISIG | Enable signals INTR, QUIT, [D]SUSP. |
| ISTRIP | Strip 8th bit off characters. |
| IUCLC | Translate uppercase characters to lowercase. |
| IXANY | Any char will restart after stop. |
| IXOFF | Enable input flow control. |
| IXON | Enable output flow control. |
| NOFLSH | Don't flush after interrupt. |
| OCRNL | Translate carriage return to newline (output). |
| OLCUC | Convert lowercase to uppercase. |
| ONLCR | Map NL to CR-NL. |
| ONLRET | Newline performs a carriage return (output). |
| ONOCR | Translate newline to carriage return-newline (output). |
| OPOST | Enable output processing. |
| PARENB | Parity enable. |
| PARMRK | Mark parity and framing errors. |
| PARODD | Odd parity, else even. |
| PENDIN | Retype pending input. |
| TOSTOP | Stop background jobs from output. |
| TTY_OP_ISPEED | Specifies the input baud rate in bits per second. |
| TTY_OP_OSPEED | Specifies the output baud rate in bits per second. |
| VDISCARD | Toggles the flushing of terminal output. |
| VDSUSP | Another suspend character. |
| VEOF | End-of-file character (sends EOF from the terminal). |
| VEOL2 | Additional end-of-line character. |
| VEOL | End-of-line character in addition to carriage return and/or linefeed. |
| VERASE | Erase the character to left of the cursor. |
| VFLUSH | Character to flush output. |
| VINTR | Interrupt character; 255 if none. Similarly for the other characters. Not all of these characters are supported on all systems. |
| VKILL | Kill the current input line. |
| VLNEXT | Enter the next character typed literally, even if it is a special character |
| VQUIT | The quit character (sends SIGQUIT signal on POSIX systems). |
| VREPRINT | Reprints the current input line. |
| VSTART | Continues paused output (normally control-Q). |
| VSTATUS | Prints system status line (load, command, pid, etc). |
| VSTOP | Pauses output (normally control-S). |
| VSUSP | Suspends the current program. |
| VSWTCH | Switch to a different shell layer. |
| VWERASE | Erases a word left of cursor. |
| XCASE | Enable input and output of uppercase characters by preceding their lowercase equivalents with "". |
http.Agent instance used to tunnel an HTTP connection over SSH. sshConfig is what is passed to client.connect() and agentOptions is passed to the http.Agent constructor.https.Agent instance used to tunnel an HTTP connection over SSH. sshConfig is what is passed to client.connect() and agentOptions is passed to the https.Agent constructor.generateKeyPair(< string >keyType[, < object >options], < function >callback) - (void) - Generates an SSH key pair of the given type. keyType may be one of 'rsa', 'ecdsa', or 'ed25519' (node.js v12+). callback has the signature (err, keys) where keys is an object containing private and public properties containing the generated SSH keys. options may contain:
bits - integer - For ECDSA and RSA keys, this is the key strength. For ECDSA, this is restricted to 256, 384, or 521. Default: (none)
cipher - string - The (SSH, not OpenSSL) cipher to use to encrypt the key. Default: (none)
comment - string - A comment to include in the private and public keys. Default: ''
format - string - The SSH key format to use. Currently only 'new' is supported, which represents the current OpenSSH key formats. Default: 'new'
passphrase - mixed - The desired passphrase for encrypting the key. This can either be a string or Buffer. Default: (none)
rounds - integer - For 'new'-formatted SSH keys, this is the number of bcrypt rounds to use when generating cipher parameters for encrypted keys. Default: 16
generateKeyPairSync(< string >keyType[, < object >options]) - object - Generates an SSH key pair of the given type. This is a synchronous version of generateKeyPair().
parseKey(< mixed >keyData[, < string >passphrase]) - mixed - Parses a private/public key in OpenSSH, RFC4716, or PPK format. For encrypted private keys, the key will be decrypted with the given passphrase. keyData can be a Buffer or string value containing the key contents. The returned value will be an array of objects (currently in the case of modern OpenSSH keys) or an object with these properties and methods:
comment - string - The comment for the key
equals(< mixed >otherKey) - boolean - This returns true if otherKey (a parsed or parseable key) is the same as this key. This method does not compare the keys' comments
getPrivatePEM() - string - This returns the PEM version of a private key
getPublicPEM() - string - This returns the PEM version of a public key (for either public key or derived from a private key)
getPublicSSH() - string - This returns the SSH version of a public key (for either public key or derived from a private key)
isPrivateKey() - boolean - This returns true if the key is a private key or not
sign(< mixed >data) - mixed - This signs the given data using this key and returns a Buffer containing the signature on success. On failure, an Error will be returned. data can be anything accepted by node's sign.update().
type - string - The full key type (e.g. 'ssh-rsa')
verify(< mixed >data, < Buffer >signature) - mixed - This verifies a signature of the given data using this key and returns true if the signature could be verified. On failure, either false will be returned or an Error will be returned upon a more critical failure. data can be anything accepted by node's verify.update().
sftp.OPEN_MODE - OPEN_MODE
sftp.STATUS_CODE - STATUS_CODE
sftp.flagsToString - flagsToString()
sftp.stringToFlags - stringToFlags()
identities(< opaque >request) - (Server mode only) The client has requested a list of public keys stored in the agent. Use failureReply() or getIdentitiesReply() to reply appropriately.
sign(< opaque >request, < mixed >pubKey, < Buffer >data, < object >options) - (Server mode only) The client has requested data to be signed using the key identified by pubKey. Use failureReply() or signReply() to reply appropriately. options may contain any of:
'sha256' or 'sha512' for RSA keys.(constructor)(< boolean >isClient) - Creates and returns a new AgentProtocol instance. isClient determines whether the instance operates in client or server mode.
failureReply(< opaque >request) - (void) - (Server mode only) Replies to the given request with a failure response.
getIdentities(< function >callback) - (void) - (Client mode only) Requests a list of public keys from the agent. callback is passed (err, keys) where keys is a possible array of public keys for authentication.
getIdentitiesReply(< opaque >request, < array >keys) - (void) - (Server mode only) Responds to a identities list request with the given array of keys in keys.
sign(< mixed >pubKey, < Buffer >data, < object >options, < function >callback) - (void) - (Client mode only) Requests that the agent sign data using the key identified by pubKey. pubKey can be any parsed (using utils.parseKey()) or parseable key value. callback is passed (err, signature) where signature is a possible Buffer containing the signature for the data. options may contain any of:
'sha256' or 'sha512' for RSA keys.signReply(< opaque >request, < Buffer >signature) - (void) - (Server mode only) Responds to a sign request with the given signature in signature.
In order to create a custom agent, your class must:
Extend BaseAgent
Call super() in its constructor
Implement at least the following methods:
getIdentities(< function >callback) - (void) - Passes (err, keys) to callback where keys is a possible array of public keys for authentication.
sign(< mixed >pubKey, < Buffer >data, < object >options, < function >callback) - (void) - Signs data using the key identified by pubKey. pubKey can be any parsed (using utils.parseKey()) or parseable key value. callback should be passed (err, signature) where signature is a possible Buffer containing the signature for the data. options may contain any of:
'sha256' or 'sha512' for RSA keys.Additionally your class may implement the following method in order to support agent forwarding on the client:
(err, stream) to callback where stream is a possible Duplex stream to be used to communicate with your agent. You will probably want to utilize AgentProtocol as agent forwarding is an OpenSSH feature, so the stream needs to be able to transmit/receive OpenSSH agent protocol packets.Client's agent configuration option: if the platform is Windows and it's the value "pageant", it creates a PageantAgent, otherwise if it's not a path to a Windows pipe it creates a CygwinAgent. In all other cases, it creates an OpenSSHAgent.socketPath in a Cygwin environment.socketPath.FAQs
SSH2 client and server modules written in pure JavaScript for node.js
The npm package ssh2 receives a total of 1,205,246 weekly downloads. As such, ssh2 popularity was classified as popular.
We found that ssh2 demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.